home *** CD-ROM | disk | FTP | other *** search
/ Merciful 2 / Merciful - Disc 2.iso / software / m / muiv3.1cracked.lha / MUI / Developer / Autodocs / MUI_List.doc < prev    next >
Text File  |  1995-11-22  |  29KB  |  1,071 lines
  1. TABLE OF CONTENTS
  2.  
  3. List.mui/List.mui
  4. List.mui/MUIA_List_Active
  5. List.mui/MUIA_List_AdjustHeight
  6. List.mui/MUIA_List_AdjustWidth
  7. List.mui/MUIA_List_AutoVisible
  8. List.mui/MUIA_List_CompareHook
  9. List.mui/MUIA_List_ConstructHook
  10. List.mui/MUIA_List_DestructHook
  11. List.mui/MUIA_List_DisplayHook
  12. List.mui/MUIA_List_DragSortable
  13. List.mui/MUIA_List_DropMark
  14. List.mui/MUIA_List_Entries
  15. List.mui/MUIA_List_First
  16. List.mui/MUIA_List_Format
  17. List.mui/MUIA_List_InsertPosition
  18. List.mui/MUIA_List_MinLineHeight
  19. List.mui/MUIA_List_MultiTestHook
  20. List.mui/MUIA_List_Quiet
  21. List.mui/MUIA_List_ShowDropMarks
  22. List.mui/MUIA_List_SourceArray
  23. List.mui/MUIA_List_Title
  24. List.mui/MUIA_List_Visible
  25. List.mui/MUIM_List_Clear
  26. List.mui/MUIM_List_CreateImage
  27. List.mui/MUIM_List_DeleteImage
  28. List.mui/MUIM_List_Exchange
  29. List.mui/MUIM_List_GetEntry
  30. List.mui/MUIM_List_Insert
  31. List.mui/MUIM_List_InsertSingle
  32. List.mui/MUIM_List_Jump
  33. List.mui/MUIM_List_Move
  34. List.mui/MUIM_List_NextSelected
  35. List.mui/MUIM_List_Redraw
  36. List.mui/MUIM_List_Remove
  37. List.mui/MUIM_List_Select
  38. List.mui/MUIM_List_Sort
  39. List.mui/MUIM_List_TestPos
  40. List.mui/List.mui
  41.  
  42.     MUI's list class is very powerful. It handles all types
  43.     of entries, from a simple string to a complicated structure
  44.     with many associated resources. Multi column lists are
  45.     also supported, the format for a column is adjustable.
  46.  
  47.     Lists support any kind of sorting, multi selection and
  48.     an active entry that can be controlled with the mouse
  49.     or the cursor keys.
  50.  
  51.     Note: A list object alone doesn't make much sense, you
  52.           should always use it as child of a listview object.
  53.           This one attaches a scrollbar and handles all user
  54.           input.
  55. List.mui/MUIA_List_Active
  56.  
  57.     NAME
  58.     MUIA_List_Active -- (V4 ) [ISG], LONG
  59.  
  60.     SPECIAL INPUTS
  61.     MUIV_List_Active_Off
  62.     MUIV_List_Active_Top
  63.     MUIV_List_Active_Bottom
  64.     MUIV_List_Active_Up
  65.     MUIV_List_Active_Down
  66.     MUIV_List_Active_PageUp
  67.     MUIV_List_Active_PageDown
  68.  
  69.     FUNCTION
  70.     Reading this attribute will return the number of
  71.     the active entry (the one with the cursor on it).
  72.     The result is between 0 and MUIA_List_Entries-1
  73.     or MUIV_List_Active_Off, in which case there is
  74.     currently no active entry.
  75.  
  76.     Setting the attribute will cause the list to
  77.     move the cursor to the new position and scroll
  78.     this position into the visible area.
  79.  
  80.     SEE ALSO
  81.     MUIA_List_Entries, MUIA_List_First, MUIA_List_Visible
  82. List.mui/MUIA_List_AdjustHeight
  83.  
  84.     NAME
  85.     MUIA_List_AdjustHeight -- (V4 ) [I..], BOOL
  86.  
  87.     FUNCTION
  88.     A list with MUIA_List_AdjustHeight set to true is exactly
  89.     as high as all of its entries and not resizable. This is
  90.     only possible when the list is filled *before* the window
  91.     is opened.
  92.  
  93.     SEE ALSO
  94.     MUIA_List_AdjustWidth
  95. List.mui/MUIA_List_AdjustWidth
  96.  
  97.     NAME
  98.     MUIA_List_AdjustWidth -- (V4 ) [I..], BOOL
  99.  
  100.     FUNCTION
  101.     A list with MUIA_List_AdjustWidth set to true is exactly
  102.     as wide as the widest entry and not resizable. This is
  103.     only possible when the list is filled *before* the window
  104.     is opened.
  105.  
  106.     SEE ALSO
  107.     MUIA_List_AdjustHeight
  108. List.mui/MUIA_List_AutoVisible
  109.  
  110.     NAME
  111.     MUIA_List_AutoVisible -- (V11) [ISG], BOOL
  112.  
  113.     FUNCTION
  114.     Set this to make your lists automatically jump to the
  115.     active entry when they are displayed.
  116.  
  117.     SEE ALSO
  118.     MUIA_List_Active
  119. List.mui/MUIA_List_CompareHook
  120.  
  121.     NAME
  122.     MUIA_List_CompareHook -- (V4 ) [IS.], struct Hook *
  123.  
  124.     FUNCTION
  125.     If you plan to have the entries of your list sorted
  126.     (either by inserting them sorted or by using the
  127.     MUIM_List_Sort method) and if the entries of your
  128.     list are not simple strings, you *must* supply
  129.     a compare hook.
  130.  
  131.     This hook will be called with one list element in A1
  132.     and another one in A2. You should return something like
  133.  
  134.     <0   e1 <  e2
  135.      0   e1 == e2
  136.     >0   e1 >  e2
  137.  
  138.     EXAMPLE
  139.     /* the builtin string compare function */
  140.  
  141.         LONG __asm cmpfunc(_a1 char *s1,_a2 char *s2)
  142.     {
  143.        return(stricmp(s1,s2));
  144.     }
  145.  
  146.     SEE ALSO
  147.     MUIA_List_ConstructHook, MUIA_List_DestructHook
  148. List.mui/MUIA_List_ConstructHook
  149.  
  150.     NAME
  151.     MUIA_List_ConstructHook -- (V4 ) [IS.], struct Hook *
  152.  
  153.     SPECIAL INPUTS
  154.     MUIV_List_ConstructHook_String
  155.  
  156.     FUNCTION
  157.     The construct hook is called whenever you add an
  158.     entry to your list. MUI will not insert the given
  159.     pointer directly, but instead call the construct
  160.     hook and add its result code.
  161.  
  162.     Imagine you want to display a list of entries
  163.     in a directory. You could step through it
  164.     using Examine()/ExNext() and directly use the
  165.     MUIM_List_Insert method on your file info block
  166.     buffer.
  167.  
  168.     Your construct hook will be called with this
  169.     file info block as parameter, makes a copy of
  170.     it and returns the address of that copy. Thats
  171.     what is actually added to the list.
  172.  
  173.     The corresponding destruct hook is called whenever
  174.     an entry shall be removed. It's task would simply be
  175.     to free the memory and maybe other resources concering
  176.     this entry that were allocated by the construct hook.
  177.  
  178.     Using these two functions, you will never have to
  179.     worry about freeing the memory used by your list
  180.     entries. Clearing the list or disposing the list
  181.     object will automatically remove all entries and
  182.     thus free the associated resources.
  183.  
  184.     The construct hook will be called with the hook
  185.     in A0, the data given to MUIM_List_Insert as message
  186.     in register A1 and with pointer to a standard kick 3.x
  187.     memory pool in A2. If you want, you can use the exec
  188.     or amiga.lib functions for allocating memory within
  189.     this pool, but this is only an option.
  190.  
  191.     If the construct hook returns NULL, nothing will be
  192.     added to the list.
  193.  
  194.     There is a builtin construct hook available called
  195.     MUIV_List_ConstructHook_String. This expects that
  196.     you only add strings to your list and will make
  197.     a local copy of this string to allow you destroying
  198.     the original. Of course you *must* also use
  199.     MUIV_List_DestructHook_String in this case.
  200.  
  201.     Without construct and destruct hooks, you are responsible
  202.     for allocating and freeing entries yourself.
  203.  
  204.     EXAMPLE
  205.     /* the builtin string construct and destruct functions: */
  206.  
  207.     APTR __asm consfunc(_a2 APTR pool,_a1 char *str)
  208.     {
  209.        char *new;
  210.        if (new=AllocPooled(pool,strlen(str)+1))
  211.           strcpy(new,str);
  212.        return(new);
  213.     }
  214.  
  215.     VOID __asm desfunc(_a2 APTR pool,_a1 char *entry)
  216.     {
  217.        FreePooled(pool,entry,strlen(entry)+1);
  218.     }
  219.  
  220.     /* for more sophisticated hooks see demo program WbMan.c */
  221.  
  222.     SEE ALSO
  223.     MUIA_List_DestructHook, MUIA_List_DisplayHook
  224. List.mui/MUIA_List_DestructHook
  225.  
  226.     NAME
  227.     MUIA_List_DestructHook -- (V4 ) [IS.], struct Hook *
  228.  
  229.     SPECIAL INPUTS
  230.     MUIV_List_DestructHook_String
  231.  
  232.     FUNCTION
  233.     Set up a destruct hook for your list. For detailed
  234.     explanation see MUIA_List_ConstructHook.
  235.  
  236.     SEE ALSO
  237.     MUIA_List_ConstructHook, MUIA_List_DisplayHook
  238. List.mui/MUIA_List_DisplayHook
  239.  
  240.     NAME
  241.     MUIA_List_DisplayHook -- (V4 ) [IS.], struct Hook *
  242.  
  243.     FUNCTION
  244.     Since MUI's lists can handle any kind of entries,
  245.     you have to supply a display hook to specify what
  246.     should actually be shown in the display.
  247.  
  248.     The hook will be called with a pointer to the
  249.     entry to be displayed in A1 and a pointer to
  250.     a string array containing as many entries as
  251.     your list may have columns in A2.
  252.  
  253.     You must fill this array with the strings that
  254.     you want to display.
  255.  
  256.     Note: You can of course use MUI's text engine
  257.           facilities here to create e.g. right aligned
  258.           or centered columns.
  259.  
  260.     Without a display hook, MUI expects a simple one
  261.     columned string list.
  262.  
  263.     See MUIA_List_Format for details about column handling.
  264.  
  265.     Note: Since version 6 of MUI, the display hook also gets the
  266.         position of the current entry as additional parameter. You
  267.     can easily do e.g. some line numbering using this feature. The
  268.     number (from 0 to NumEntries-1) is stored in the longword
  269.     *preceding* the column array (see example below).
  270.  
  271.     EXAMPLE
  272.     /* list of file info blocks, two columned, name and size */
  273.  
  274.     LONG __asm dispfunc(_a2 char **array,_a1 struct FileInfoBlock *fib)
  275.     {
  276.        static char buf1[20],buf2[20];
  277.  
  278.        if (fib->fib_EntryType<0)
  279.          sprintf(buf2,"\33r%ld",fib->fib_Size);
  280.        else
  281.          strcpy(buf2,"\33r(dir)");
  282.  
  283.        sprintf(buf1,"%ld",array[-1]);   // get the line number.
  284.  
  285.        *array++ = buf1;
  286.        *array++ = fib->fib_FileName;
  287.        *array   = buf2;
  288.  
  289.        return(0);
  290.     }
  291.  
  292.     SEE ALSO
  293.     MUIA_List_Format, MUIA_Text_Contents
  294. List.mui/MUIA_List_DragSortable
  295.  
  296.     NAME
  297.     MUIA_List_DragSortable -- (V11) [ISG], BOOL
  298.  
  299.     FUNCTION
  300.     If you set this attribute to TRUE, the user will be able
  301.     to move around entries in the list by using drag&drop.
  302. List.mui/MUIA_List_DropMark
  303.  
  304.     NAME
  305.     MUIA_List_DropMark -- (V11) [..G], LONG
  306.  
  307.     FUNCTION
  308.     After a successfull drop operation, this attribute holds
  309.     the position where we should insert the new entry(ies).
  310.     
  311.     EXAMPLE
  312.     See DragnDrop example program
  313. List.mui/MUIA_List_Entries
  314.  
  315.     NAME
  316.     MUIA_List_Entries -- (V4 ) [..G], LONG
  317.  
  318.     FUNCTION
  319.     Get the current number of entries in the list.
  320.  
  321.     SEE ALSO
  322.     MUIA_List_First, MUIA_List_Visible, MUIA_List_Active
  323. List.mui/MUIA_List_First
  324.  
  325.     NAME
  326.     MUIA_List_First -- (V4 ) [..G], LONG
  327.  
  328.     FUNCTION
  329.     Get the number of the entry displayed on top of
  330.     the list. You have to be prepared to get a result
  331.     of -1, which means that the list is not visible
  332.     at all (e.g. when the window is iconifed).
  333.  
  334.     SEE ALSO
  335.     MUIA_List_Visible, MUIA_List_Entries, MUIA_List_Active
  336. List.mui/MUIA_List_Format
  337.  
  338.     NAME
  339.     MUIA_List_Format -- (V4 ) [ISG], STRPTR
  340.  
  341. 8    FUNCTION
  342.     MUI has the ability to handle multi column lists. To define
  343.     how many columns should be displayed and how they should be
  344.     formatted, you specify a format string.
  345.  
  346.     This format string must contain one entry for each column
  347.     you want to see. Entries are seperated by commas, one
  348.     entry is parsed via dos.library/ReadArgs().
  349.  
  350.     The template for a single entry looks like this:
  351.  
  352.     DELTA=D/N,PREPARSE=P/K,WEIGHT=W/N,
  353.     MINWIDTH=MIW/N,MAXWIDTH=MAW/N,COL=C/N,BAR/S
  354.  
  355.     DELTA
  356.        Space in pixel between this column and the next.
  357.        the last displayed column ignores this setting.
  358.        Defaults to 4.
  359.  
  360.     PREPARSE
  361.        A preparse value for this column. Setting this
  362.        e.g. to "\33c" would make the column centered.
  363.        See MUIA_Text_Contents for other control codes.
  364.  
  365.     WEIGHT
  366.        The weight of the column. As with MUI's group
  367.        class, columns are layouted with a minimum
  368.        size, a maximum size and weight. A column with
  369.        a weight of 200 would gain twice the space than
  370.        a column with a weight of 100.
  371.        Defaults to 100.
  372.  
  373.     MINWIDTH
  374.        Minimum percentage width for the current column.
  375.        If your list is 200 pixel wide and you set this
  376.        to 25, your column will at least be 50 pixel.
  377.        The special value -1 for this parameter means that
  378.        the minimum width is as wide as the widest entry in
  379.        this column. This ensures that every entry will be
  380.        completely visible (as long as the list is wide enough).
  381.        Defaults to -1.
  382.  
  383.     MAXWIDTH
  384.        Maximum percentage width for the current column.
  385.        If your list is 200 pixel wide and you set this
  386.        to 25, your column will not be wider as 50 pixel.
  387.        The special value -1 for this parameter means that
  388.        the maximum width is as wide as the widest entry in
  389.        this column.
  390.        Defaults to -1.
  391.  
  392.     COL
  393.        This value adjusts the number of the current column.
  394.        This allows you to adjust the order of your columns
  395.        without having to change your display hook. See
  396.        example for details.
  397.        Defaults to current entry number (0,1,...)
  398.  
  399.     BAR
  400.        Since muimaster.library V11, you can enable a
  401.        vertical bar between this and the next column by
  402.        using this switch.
  403.  
  404.     If your list object gets so small there is not enough
  405.     place for the minwidth of a column, this column will
  406.     be hidden completely and the remaining space is
  407.     distributed between the remaining columns. This is not
  408.     true if the column is the first column, in this case
  409.     the entries will simply be clipped.
  410.  
  411.     Note: You will have as many columns in your list as
  412.           entries in the format string (i.e. number of
  413.           commas + 1). Empty entries, e.g. with a format
  414.           string of ",,,," are perfectly ok.
  415.  
  416.     The default list format is an empty string (""), this
  417.     means a one column list without special formatting.
  418.  
  419.     BUGS
  420.     Currently there is a maximum of 64 columns for a list.
  421.  
  422.     EXAMPLE
  423.     /* Three column list without further formatting: */
  424.     MUIA_List_Format: ",,"
  425.  
  426.     /* Three column list, middle column centered: */
  427.     MUIA_List_Format: ",P=\33c,"
  428.  
  429.     /* Three column list, display order 2 1 0: */
  430.     MUIA_List_Format: "COL=2,COL=1,COL=0"
  431.  
  432.     /* now something more complex.           */
  433.     /* the display hook defines six entries: */
  434.     dispfunc(_a2 char **array,_a1 struct Article *at)
  435.     {
  436.        *array++ = at->FromName; // col 0
  437.        *array++ = at->FromPath; // col 1
  438.        *array++ = at->ToName;   // col 2
  439.        *array++ = at->ToPath;   // col 3
  440.        *array++ = at->Date;     // col 4
  441.        *array   = at->Subject;  // col 5
  442.     }
  443.  
  444.     /* but we only want to have fromname, date and subject
  445.     /* actually displayed, subject shoud be centered: */
  446.     MUIA_List_Format, "COL=0,COL=4,COL=5 P=\33c"
  447.  
  448.     /* maybe this looks kind of silly, why not make our  */
  449.     /* display hook only fill in these three columns.    */
  450.     /* well, if you would e.g. make the format string    */
  451.     /* user configurable and document what your display  */
  452.     /* hook puts into the array, the user could decide   */
  453.     /* what columns he actually wants to see.            */
  454.     /* The supplied example DFView does something like   */
  455.     /* that.                                             */
  456.  
  457.     /* two column list:   ! Eye    1234 !
  458.                               ! Foot     22 !
  459.                               ! Nose  22331 ! */
  460.  
  461.     MUIA_List_Format, "MAW=100,P=\33r"
  462.  
  463.     SEE ALSO
  464.     MUIA_List_DisplayHook, MUIA_Text_Contents
  465. List.mui/MUIA_List_InsertPosition
  466.  
  467.     NAME
  468.     MUIA_List_InsertPosition -- (V9 ) [..G], LONG
  469.  
  470.     FUNCTION
  471.     After insertion of an element with MUIM_List_Insert,
  472.     you can query the position of the new entry by
  473.     getting this attribute.
  474. List.mui/MUIA_List_MinLineHeight
  475.  
  476.     NAME
  477.     MUIA_List_MinLineHeight -- (V4 ) [I..], LONG
  478.  
  479.     FUNCTION
  480.     Sets the minimum line height for lists in pixels. Useful
  481.     e.g. if you have custom images.
  482. List.mui/MUIA_List_MultiTestHook
  483.  
  484.     NAME
  485.     MUIA_List_MultiTestHook -- (V4 ) [IS.], struct Hook *
  486.  
  487.     FUNCTION
  488.     If you plan to have a multi selecting list but not
  489.     all of your entries are actually multi selectable
  490.     (e.g. in a file requester), you can supply a
  491.     MUIA_List_MultiTestHook.
  492.  
  493.     It will be called with a pointer to an entry in
  494.     A1 and should return TRUE if the entry is multi
  495.     selectable, FALSE otherwise.
  496.  
  497.     EXAMPLE
  498.     /* multi test func for a list of file info blocks */
  499.  
  500.     LONG __asm mtfunc(_a1 struct FileInfoBlock *fib)
  501.     {
  502.        if (fib->fib_DirEntryType<0)
  503.           return(TRUE);
  504.        else
  505.           return(FALSE);
  506.     }
  507.  
  508.     SEE ALSO
  509.     MUIA_List_ConstructHook, MUIA_List_DestructHook
  510. List.mui/MUIA_List_Quiet
  511.  
  512.     NAME
  513.     MUIA_List_Quiet -- (V4 ) [.S.], BOOL
  514.  
  515.     FUNCTION
  516.     If you add/remove lots of entries to/from a currently visible
  517.     list, this will cause lots of screen action and slow down
  518.     the operation. Setting MUIA_List_Quiet to true will
  519.     temporarily prevent the list from being refreshed, this
  520.     refresh will take place only once when you set it back
  521.     to false again.
  522.  
  523.     EXAMPLE
  524.     set(list,MUIA_List_Quiet,TRUE);
  525.     AddThousandEntries(list);
  526.     set(list,MUIA_List_Quiet,FALSE);
  527.  
  528.     SEE ALSO
  529.     MUIM_List_Insert, MUIM_List_Remove
  530. List.mui/MUIA_List_ShowDropMarks
  531.  
  532.     NAME
  533.     MUIA_List_ShowDropMarks -- (V11) [ISG], BOOL
  534.  
  535.     FUNCTION
  536.     If a list supports Drag & Drop, it usually indicates the place
  537.     where a new line would be inserted with some horizontal lines.
  538.  
  539.     Showing this place doesnt make much sense if you dont care
  540.     about the drop position anyway, e.g. because your list is
  541.     always alphabetically sorted. You should set this attribute
  542.     to FALSE in these cases.
  543.  
  544.     SEE ALSO
  545.     MUIA_List_DropMark
  546. List.mui/MUIA_List_SourceArray
  547.  
  548.     NAME
  549.     MUIA_List_SourceArray -- (V4 ) [I..], APTR
  550.  
  551.     FUNCTION
  552.     The NULL terminated array given here is immediately inserted into the
  553.     list after object creation time.
  554.  
  555.     EXAMPLE
  556.     static const char *KeyList[] =
  557.     {
  558.        "Cursor Up",
  559.        "Cursor Down",
  560.        "Cursor Left",
  561.        "Cursor Right",
  562.        NULL;
  563.     };
  564.  
  565.     LV_Keys = ListviewObject,
  566.        MUIA_Listview_List, ListObject,
  567.           InputListFrame,
  568.           MUIA_List_AdjustWidth, TRUE,
  569.           MUIA_List_SourceArray, KeyList,
  570.           End,
  571.        End;
  572. List.mui/MUIA_List_Title
  573.  
  574.     NAME
  575.     MUIA_List_Title -- (V6 ) [ISG], char *
  576.  
  577.     FUNCTION
  578.     Specify a title for the current list. The title is displayed
  579.     at the very first line and doesn't scroll away when the list
  580.     top position moves.
  581.  
  582.     Usually, the title is just a string. However, if you have
  583.     a multi column list with a custom display hook and you
  584.     want to have seperate titles for each of your columns,
  585.     you can set this attribute to TRUE. In this case, whenever
  586.     MUI feels that the list title has to be drawn, it will
  587.     call your display hook with a NULL entry pointer. Your
  588.     hook has to check for this NULL entry and fill the
  589.     given string array with your column titles. Layout of
  590.     the column titles follows the same rules as layout
  591.     of the lists entries.
  592.  
  593.     EXAMPLE
  594.  
  595.     /* display function for a multi columned file list with titles */
  596.  
  597.     LONG __asm DisplayFunc(_a2 char **array,_a1 struct Entry *e)
  598.     {
  599.        struct Data *data = hook->h_Data;
  600.  
  601.        if (e)
  602.        {
  603.           *array++ = e->Name;
  604.           *array++ = e->Size;
  605.           *array++ = e->Date;
  606.           *array++ = e->Time;
  607.           *array++ = e->Flags;
  608.           *array   = e->Comment;
  609.        }
  610.        else
  611.        {
  612.           *array++ = "Name";
  613.           *array++ = "Size";
  614.           *array++ = "Date";
  615.           *array++ = "Time";
  616.           *array++ = "Flags";
  617.           *array   = "Comment";
  618.        }
  619.  
  620.        return(0);
  621.     }
  622.  
  623.     SEE ALSO
  624.     MUIA_List_DisplayHook
  625. List.mui/MUIA_List_Visible
  626.  
  627.     NAME
  628.     MUIA_List_Visible -- (V4 ) [..G], LONG
  629.  
  630.     FUNCTION
  631.     Get the current number of visible entries in the list.
  632.     You have to be prepared to get a result
  633.     of -1, which means that the list is not visible
  634.     at all (e.g. when the window is iconifed).
  635.  
  636.     SEE ALSO
  637.     MUIA_List_First, MUIA_List_Entries, MUIA_List_Active
  638. List.mui/MUIM_List_Clear
  639.  
  640.     NAME
  641.     MUIM_List_Clear (V4 )
  642.  
  643.     SYNOPSIS
  644.     DoMethod(obj,MUIM_List_Clear,);
  645.  
  646.     FUNCTION
  647.     Clear the list, all entries are removed. If a destruct
  648.     hook is set it will be called for every entry.
  649.  
  650.     SEE ALSO
  651.     MUIM_List_Insert, MUIA_List_DestructHook
  652. List.mui/MUIM_List_CreateImage
  653.  
  654.     NAME
  655.     MUIM_List_CreateImage (V11)
  656.  
  657.     SYNOPSIS
  658.     DoMethod(obj,MUIM_List_CreateImage,Object *obj, ULONG flags);
  659.  
  660.     FUNCTION
  661.     If you want to have custom images in a listview (e.g.
  662.     like the little monitor icons in PSI), you should create
  663.     them as Bitmap objects (or Bodychunk objects) in the
  664.     setup method of your list class (use a subclass!). 
  665.  
  666.     After that, pass the newly created object pointer to
  667.     MUIM_List_CreateImage and use the result in your display
  668.     hook with
  669.  
  670.     \33O[%08lx]
  671.  
  672.     where %08lx must be replaced by the pointer you got
  673.     from MUIM_List_CreateImage.
  674.  
  675.     When your list is done (i.e. in the Cleanup method),
  676.     kill your image with MUIM_List_DeleteImage and
  677.     dispose your object.
  678.  
  679.     RESULT
  680.     The result you get is a black box pointer, it's not valid
  681.     to assume anything about it. The only useful thing you can
  682.     do is to include it in \33O[%08lx]. The result may be NULL
  683.     in which case MUI was unable to create the image, but the
  684.     \33O[] combination simply draws nothing when receiving a
  685.     NULL so it shouldnt be considered an error.
  686.  
  687.     EXAMPLE
  688.     See ScreenList class in screen inspector source code psi.c
  689.  
  690.     SEE ALSO
  691.     MUIM_List_DeleteImage
  692. List.mui/MUIM_List_DeleteImage
  693.  
  694.     NAME
  695.     MUIM_List_DeleteImage (V11)
  696.  
  697.     SYNOPSIS
  698.     DoMethod(obj,MUIM_List_DeleteImage,APTR listimg);
  699.  
  700.     FUNCTION
  701.     Delete the image pointer returned from MUIM_List_CreateImage.
  702.  
  703.     SEE ALSO
  704.     MUIM_List_DeleteImage
  705. List.mui/MUIM_List_Exchange
  706.  
  707.     NAME
  708.     MUIM_List_Exchange (V4 )
  709.  
  710.     SYNOPSIS
  711.     DoMethod(obj,MUIM_List_Exchange,LONG pos1, LONG pos2);
  712.  
  713.     FUNCTION
  714.     Exchange two entries in a list.
  715.  
  716.     INPUTS
  717.     pos1 - number of the first entry.
  718.     pos2 - number of the second entry.
  719.  
  720.     Possible special values since muimaster.library V9:
  721.  
  722.     MUIV_List_Exchange_Top       0
  723.     MUIV_List_Exchange_Active   -1
  724.     MUIV_List_Exchange_Bottom   -2
  725.     MUIV_List_Exchange_Next     -3 /* only valid for second parameter */
  726.     MUIV_List_Exchange_Previous -4 /* only valid for second parameter */
  727.  
  728.     SEE ALSO
  729.     MUIM_List_Insert, MUIM_List_Remove, MUIM_List_Move
  730. List.mui/MUIM_List_GetEntry
  731.  
  732.     NAME
  733.     MUIM_List_GetEntry (V4 )
  734.  
  735.     SYNOPSIS
  736.     DoMethod(obj,MUIM_List_GetEntry,LONG pos, APTR *entry);
  737.  
  738.     FUNCTION
  739.     Get an entry of a list.
  740.  
  741.     INPUTS
  742.     pos   - Number of entry, MUIV_List_GetEntry_Active can
  743.             be used to get the active entry.
  744.  
  745.     entry - Pointer to a longword where the entry will
  746.             be stored. If the entry is not available
  747.             (either because you are out of bounds or
  748.             because there is no active entry), you will
  749.             receive a NULL.
  750.  
  751.     EXAMPLE
  752.     /* iterate through a list containing file info blocks */
  753.  
  754.     for (i=0;;i++)
  755.     {
  756.         struct FileInfoBlock *fib;
  757.  
  758.         DoMethod(list,MUIM_List_GetEntry,i,&fib);
  759.         if (!fib) break;
  760.  
  761.         printf("%s\n",fib->fib_FileName);
  762.     }
  763.  
  764.     SEE ALSO
  765.     MUIM_List_Insert, MUIM_List_Remove
  766. List.mui/MUIM_List_Insert
  767.  
  768.     NAME
  769.     MUIM_List_Insert (V4 )
  770.  
  771.     SYNOPSIS
  772.     DoMethod(obj,MUIM_List_Insert,APTR *entries, LONG count, LONG pos);
  773.  
  774.     FUNCTION
  775.     Insert new entries into a list.
  776.     When the list has a construct hook, the given pointers
  777.     won't be inserted directly but instead passed through 
  778.     to the construct hook.
  779.  
  780.     INPUTS
  781.     entries - pointer to an array of pointers to be inserted.
  782.               Warning: This is a pointer to a pointer. See
  783.               example for details.
  784.  
  785.     count   - Number of elements to be inserted. If count==-1,
  786.               entries will be inserted until NULL pointer in
  787.               the entries array is found.
  788.  
  789.     pos     - New entries will be added in front of this entry.
  790.               MUIV_List_Insert_Top:
  791.                  insert as first entry.
  792.               MUIV_List_Insert_Active:
  793.                  insert in front of the active entry.
  794.               MUIV_List_Insert_Sorted:
  795.                  insert sorted.
  796.               MUIV_List_Insert_Bottom:
  797.                  insert as last entry.
  798.  
  799.     EXAMPLE
  800.     /* insert a string */
  801.     char *str = "New entry";
  802.     DoMethod(list,MUIM_List_Insert,&str,1,MUIV_List_Insert_Bottom);
  803.  
  804.     /* insert an array */
  805.     char *str[] =
  806.     {
  807.        "Entry 1",
  808.        "Entry 2",
  809.        "Entry 3",
  810.        "Entry 4",
  811.        NULL
  812.     };
  813.     DoMethod(list,MUIM_List_Insert,str,-1,MUIV_List_Insert_Bottom);
  814.  
  815.     SEE ALSO
  816.     MUIM_List_Remove, MUIA_List_ConstructHook
  817. List.mui/MUIM_List_InsertSingle
  818.  
  819.     NAME
  820.     MUIM_List_InsertSingle (V7 )
  821.  
  822.     SYNOPSIS
  823.     DoMethod(obj,MUIM_List_InsertSingle,APTR entry, LONG pos);
  824.  
  825.     FUNCTION
  826.     Insert one new entry into a list. Using MUIM_List_Insert has
  827.     caused some confusion since it takes an array to items instead
  828.     a single item. To insert single items, MUIM_List_InsertSingle
  829.     is the better choice.
  830.  
  831.     When the list has a construct hook, the given pointer
  832.     won't be inserted directly but instead passed through
  833.     to the construct hook.
  834.  
  835.     INPUTS
  836.     entry   - item to insert.
  837.  
  838.     pos     - New entry will be added in front of this entry.
  839.               MUIV_List_Insert_Top:
  840.                  insert as first entry.
  841.               MUIV_List_Insert_Active:
  842.                  insert in front of the active entry.
  843.               MUIV_List_Insert_Sorted:
  844.                  insert sorted.
  845.               MUIV_List_Insert_Bottom:
  846.                  insert as last entry.
  847.  
  848.     EXAMPLE
  849.     /* insert a string */
  850.     DoMethod(list,MUIM_List_InsertSingle,"foobar",MUIV_List_Insert_Bottom);
  851.  
  852.     SEE ALSO
  853.     MUIM_List_Remove, MUIA_List_ConstructHook, MUIM_List_InsertSingle
  854. List.mui/MUIM_List_Jump
  855.  
  856.     NAME
  857.     MUIM_List_Jump (V4 )
  858.  
  859.     SYNOPSIS
  860.     DoMethod(obj,MUIM_List_Jump,LONG pos);
  861.  
  862.     FUNCTION
  863.     Scroll any entry into the visible part of a list.
  864.  
  865.     Note: Jumping to an entry doesn't mean to make this
  866.           entry the active one. This can be done by 
  867.           setting the MUIA_List_Active attribute.
  868.  
  869.     INPUTS
  870.     pos - Number of the entry that should be made visible.
  871.           Use MUIV_List_Jump_Active to jump to the active
  872.           entry.
  873.  
  874.     EXAMPLE
  875.     /* line 42 is interesting, so make it visible */
  876.     DoMethod(list,MUIM_List_Jump,42);
  877.  
  878.     SEE ALSO
  879.     MUIA_List_Active
  880. List.mui/MUIM_List_Move
  881.  
  882.     NAME
  883.     MUIM_List_Move (V9 )
  884.  
  885.     SYNOPSIS
  886.     DoMethod(obj,MUIM_List_Move,LONG from, LONG to);
  887.  
  888.     FUNCTION
  889.     Move an entry from one position to another.
  890.  
  891.     INPUTS
  892.     pos1 - number of the first entry.
  893.     pos2 - number of the second entry.
  894.  
  895.     Possible special values since muimaster.library V9:
  896.  
  897.     MUIV_List_Move_Top       0
  898.     MUIV_List_Move_Active   -1
  899.     MUIV_List_Move_Bottom   -2
  900.     MUIV_List_Move_Next     -3 /* only valid for second parameter */
  901.     MUIV_List_Move_Previous -4 /* only valid for second parameter */
  902.  
  903.     SEE ALSO
  904.     MUIM_List_Insert, MUIM_List_Remove, MUIM_List_Exchange
  905. List.mui/MUIM_List_NextSelected
  906.  
  907.     NAME
  908.     MUIM_List_NextSelected (V6 )
  909.  
  910.     SYNOPSIS
  911.     DoMethod(obj,MUIM_List_NextSelected,LONG *pos);
  912.  
  913.     FUNCTION
  914.     Iterate through the selected entries of a list.
  915.     This method steps through the contents of a (multi
  916.     select) list and returns every entry that is currently
  917.     selected. When no entry is selected but an entry is
  918.     active, only the active entry will be returned.
  919.  
  920.     This behaviour will result in not returning the
  921.     active entry when you have some other selected
  922.     entries somewhere in your list. Since the active
  923.     entry just acts as some kind of cursor mark,
  924.     this seems to be the only sensible possibility
  925.     to handle multi selection together with keyboard
  926.     control.
  927.  
  928.     INPUTS
  929.     pos - a pointer to longword that will hold the number
  930.           of the returned entry. Must be set to 
  931.           MUIV_List_NextSelected_Start at start of iteration. 
  932.           Is set to MUIV_List_NextSelected_End when iteration
  933.           is finished.
  934.  
  935.     EXAMPLE
  936.  
  937.     /* Iterate through a list with FileInfoBlocks */
  938.  
  939.     struct FileInfoBlock *fib;
  940.     LONG id = MUIV_List_NextSelected_Start;
  941.  
  942.     for (;;)
  943.     {
  944.        DoMethod(list,MUIM_List_NextSelected,&id);
  945.        if (id==MUIV_List_NextSelected_End) break;
  946.  
  947.        DoMethod(list,MUIM_List_GetEntry,id,&fib);
  948.        printf("selected: %s\n",fib->fib_FileName);
  949.     }
  950.  
  951.  
  952.     SEE ALSO
  953.     MUIM_List_Select
  954. List.mui/MUIM_List_Redraw
  955.  
  956.     NAME
  957.     MUIM_List_Redraw (V4 )
  958.  
  959.     SYNOPSIS
  960.     DoMethod(obj,MUIM_List_Redraw,LONG pos);
  961.  
  962.     FUNCTION
  963.     If you made some changes to an entry of your list and
  964.     want these changes to be shown in the display, you will
  965.     have to call this method.
  966.  
  967.     INPUTS
  968.     pos - Number of the line to redraw. When the line is not
  969.           currently visible, nothing will happen. Specials:
  970.           MUIV_List_Redraw_Active:
  971.              redraw the active line (if any),
  972.           MUIV_List_Redraw_All:
  973.              redraw all lines.
  974.  
  975.     EXAMPLE
  976.     /* do a complete refresh: */
  977.     DoMethod(list,MUIM_List_Redraw,MUIV_List_Redraw_All);
  978. List.mui/MUIM_List_Remove
  979.  
  980.     NAME
  981.     MUIM_List_Remove (V4 )
  982.  
  983.     SYNOPSIS
  984.     DoMethod(obj,MUIM_List_Remove,LONG pos);
  985.  
  986.     FUNCTION
  987.     Remove an entry from a list.
  988.  
  989.     INPUTS
  990.     pos - number of the entry to be removed or one of
  991.           MUIV_List_Remove_First,
  992.           MUIV_List_Remove_Active,
  993.           MUIV_List_Remove_Last.
  994.           When the active entry is removed, the following entry
  995.           will become active.
  996.  
  997.     EXAMPLE
  998.     /* when delete is pressed, remove the active entry */
  999.     DoMethod(btdel,MUIM_Notify,MUIA_Pressed,FALSE,
  1000.        list,2,MUIM_List_Remove,MUIV_List_Remove_Active);
  1001.  
  1002.     SEE ALSO
  1003.     MUIM_List_Insert, MUIA_List_DestructHook
  1004. List.mui/MUIM_List_Select
  1005.  
  1006.     NAME
  1007.     MUIM_List_Select (V4 )
  1008.  
  1009.     SYNOPSIS
  1010.     DoMethod(obj,MUIM_List_Select,LONG pos, LONG seltype, LONG *state);
  1011.  
  1012.     FUNCTION
  1013.     Select/deselect a list entry or ask an entry if its
  1014.     selected.
  1015.  
  1016.     INPUTS
  1017.  
  1018.     pos     - Number of the entry or
  1019.               MUIV_List_Select_Active for the active entry.
  1020.               MUIV_List_Select_All    for all entries.
  1021.  
  1022.     seltype - MUIV_List_Select_Off     unselect entry.
  1023.               MUIV_List_Select_On      select entry.
  1024.               MUIV_List_Select_Toggle  toggle entry.
  1025.               MUIV_List_Select_Ask     just ask about the state.
  1026.  
  1027.     state   - Pointer to a longword. If not NULL, this will
  1028.               be filled with the current selection state.
  1029.  
  1030.     NOTES
  1031.     Since version V9 of muimaster.library: 
  1032.     If pos==MUIV_List_Select_All and seltype==MUIV_List_Select_Ask,
  1033.     state will be filled with the total number of selected entries.
  1034.  
  1035.     EXAMPLE
  1036.     /* toggle selection state of active entry */
  1037.     DoMethod(list,MUIM_List_Select,MUIV_List_Select_Active,
  1038.        MUIV_List_Select_Toggle,NULL);
  1039.  
  1040.     /* select all entries */
  1041.     DoMethod(list,MUIM_List_Select,MUIV_List_Select_All,
  1042.        MUIV_List_Select_On,NULL);
  1043.  
  1044.     SEE ALSO
  1045.     MUIA_List_MultiTest_Hook
  1046. List.mui/MUIM_List_Sort
  1047.  
  1048.     NAME
  1049.     MUIM_List_Sort (V4 )
  1050.  
  1051.     SYNOPSIS
  1052.     DoMethod(obj,MUIM_List_Sort,);
  1053.  
  1054.     FUNCTION
  1055.     Sort the list. MUI uses an iterative quicksort algorithm,
  1056.     no stack problems will occur.
  1057.  
  1058.     SEE ALSO
  1059.     MUIA_List_CompareHook
  1060. List.mui/MUIM_List_TestPos
  1061.  
  1062.     NAME
  1063.     MUIM_List_TestPos (V11)
  1064.  
  1065.     SYNOPSIS
  1066.     DoMethod(obj,MUIM_List_TestPos,LONG x, LONG y, struct MUI_List_TestPos_Result *res);
  1067.  
  1068.     FUNCTION
  1069.     Find out which line/column of a listview is currently
  1070.     displayed at a certain position.
  1071.